Lean and DRY pass over the 0.16.0 release artifacts#2682
Merged
chalin merged 12 commits intoJul 19, 2026
Conversation
Cross-page DRY pass over the 0.16.0 release artifacts (one home per fact): - Release post: links the Hugo guide's language-API renames instead of restating them; replaces the fresh-clone setup recipe with the existing-install update step and a link to Other installation options; links Install PostCSS; the version footnote links the official support policy instead of restating it. - Changelog: drops upgrade advice from the Hugo-floor entry (the google#2593 citation moves to the language-API entry); trims the favicon filename list and discovery restatement (docs own the reference detail); tightens the PostCSS entry. - Docs: Install PostCSS now owns the Browserslist defaults compatibility statement (was stated only in the post and changelog).
- Reworks the Release summary as a selective ToC (one bullet per section with a glue clause), matching the 0.15.0 summary style; actions and details stay in their sections. - Links the two unlinked skim items in Ready to Upgrade. - Drops intra-page restatements: theme/package.json ownership was stated three times (npm-deps section is its home), and the shared chrome section stated the full-is-default fact three times and experimental twice in one paragraph. - Compresses the nested-module-tag note to its user-relevant point.
Captures the review guidance applied to the 0.16.0 post in its canonical home (Content placement): upgrade posts stay maximally actionable yet lean, the release summary reads like a selective table of contents, and each fact has one home section. Also spells out 'devs' (flagged by cspell).
Applies the same one-home-per-fact review as the release post: - Removes the trailing 'Recommended minimum Hugo version' section: it restated the intro, the Hugo-version section, and the Upgrade section, and nothing links to it. Its one unique bit, the hugoVersion.min YAML shape, moves into the Hugo-version actions. - Homes the hugo-extended and hvm install commands in the Upgrade section (they appeared twice); the Hugo-version actions link there. - Collapses the node-tools body/actions near-verbatim duplication of the 0.163.2 and 0.163.3 fix conditionals: the actions own them. - Drops vestigial 'upgrade to 0.160.1' advice from the amp-escaping and template-cleanup actions -- 0.160.1 is already the mandatory minimum -- and folds the link-render-hook shielding nuance into its action bullet. - cSpell: adds contentbasename and downscaling, pre-existing words in this file that the spell check flags.
The release and Hugo-upgrade posts are companions, published and read together, so the standalone-entry-point argument doesn't justify both posts stating the Hugo floor and target with near-identical actions. - Hugo guide: drop the Hugo-version section and its actions; the intro, a summary item, and internal anchors now link to the release post's Hugo section instead. - Release post: absorb the unique detail (validated across the project, example site, and a large downstream site) and point its actions at the guide's install commands.
The 0.152 upgrade guide rendered its recommended minimum via the hugoMinVersion site param, so the published post silently drifted from 0.157.0 to 0.160.1 when the param moved. Freeze the publish-time literals. Maintainer notes now state the rule: current-state pages (docs, the changelog's official-support section) compute versions via the param and the hugo-version shortcode; blog posts are historical snapshots and hard-code literals.
Blog posts are historical snapshots, so they must render versions time-insensitively — but scattering literals through a post makes updates (say, for a patch release) a search-and-replace exercise. Instead, declare each version a post repeats as a page param frozen in its front matter: one field to edit, and since page params take precedence over site params, the same param call is frozen in a post and live in docs. - 0.152 guide: freeze hugoMinVersion at its publish-time value (0.157.0), shadowing the site param it had silently drifted with. - 0.16.0 and Hugo 0.158+ posts: render the validated upgrade target via a frozen hugoTarget page param; narrative facts about specific releases stay literal. - Maintainer notes: document the rule. - test:hugo-versions: posts must not use the live hugo-version shortcode, and any version param a post renders must be frozen in its front matter (red-proofed against the unfrozen 0.152 post).
Name the concept — the officially supported Hugo version, per the changelog's official-support policy — rather than the param's role in one post, and echo the hugoMinVersion form.
The rule's home is the maintainer notes and the freeze is test-enforced; snapshot semantics for a version param in a dated post need no per-post explanation. Trim the test comment to a pointer for the same reason.
Companion posts declare hugoSupportedVersion independently, so a patch-time bump could update one post and miss the other. Frozen versions snapshot publish-time values: until a post is published they must match the live declarations, which transitively keeps companions in agreement. Dormant for published posts, whose values age by design. Red-proofed: bumping one companion's frozen value fails only the new test, with the missed post named.
- Drops the release post's Browserslist-defaults paragraph: the fact and the keep-PostCSS guidance live in the linked Install PostCSS docs. - Generalizes the package-layout bullet to "runtime npm dependencies": the npm-deps section owns which packages theme/package.json declares.
- Matches frozen params only where Hugo resolves them — top-level front-matter fields or direct children of params: — so a deeper-nested param (silently ignored by Hugo) no longer passes as frozen. - Requires draft-guide titles with an upper version bound (N.M.x) to cover the frozen hugoSupportedVersion, so advancing the target forces the guide's range and coverage to be reviewed. - Narrows the maintainer notes and test comment to the version params that posts render, which is what the guard covers; narrative version literals stay literal.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Applies the Content placement guidance (one home per fact; lean and DRY) to the 0.16.0 release artifacts:
defaultscompatibility statement in the docs (Install PostCSS).test:hugo-versions: frozen params must be effective (where Hugo resolves them), draft posts must freeze the currently declared values, and draft-guide title bounds must cover the frozen target.Preview: release post · Hugo guide · changelog